home *** CD-ROM | disk | FTP | other *** search
/ Scene Storm / Scene Storm - Volume 1.iso / coding / c / pdc / doc / blink.doc next >
Text File  |  1990-04-06  |  12KB  |  340 lines
  1. ============
  2. Introduction
  3. ============
  4.  
  5. BLINK is a linker written as a replacement for ALINK.  It is fully
  6. ALINK compatible accepting all command line options and WITH files. 
  7. BLINK supports many additional options not found in ALINK.
  8.  
  9. BLINK has been produce through the combined efforts of
  10.     The Software Distillery
  11.        currently comprised of:
  12.     Dave Baker
  13.     Ed Burnette
  14.     Stan Chow
  15.     Jay Denebeim
  16.     Gordon Keener
  17.     Jack Rouse
  18.     John Toebes
  19.     Doug Walker
  20.  
  21. It may be freely distributed provided:
  22.     1) No charge is made for its use or distribution
  23.     2) This manual is distributed along with the executable module
  24.     3) No modifications are made to the executable module
  25.  
  26. Failure to comply with these rules will simply work to convince people
  27. that there is no value in producing good freely redistributable software.
  28.  
  29. The latest version of BLINK and our other projects are available from
  30. our BBS:
  31.      Deep Thought     (919) 471-6436
  32. Address all correspondence to 
  33.      John Toebes
  34.      The Software Distillery
  35.      235 Trillingham Lane
  36.      Cary NC 27511
  37.  
  38. Let us know what you do and don't like about it.  There are several
  39. enhancements that WILL be out in the next major release:
  40.   * Overlay support
  41.   * Complete XREF of library references
  42.   * Additional hunk coalescing features
  43.   * More finely tuned code
  44.  
  45. ===========
  46. Using BLINK
  47. ===========
  48.  
  49. Command Line Syntax.
  50. --------------------
  51.  
  52. BLINK is driven by keyword parameters in any order indicating the
  53. action to be performed.  The basic syntax is:
  54.  
  55. BLINK [FROM][ROOT] files  [TO file][WITH file][VER file]
  56. [LIBRARY | LIB files][MAP file map_options][XREF file][options]
  57.  
  58. where:
  59.  file    means a single file
  60.  
  61.  files   means zero or more file names separated by a comma, plus sign
  62.          or space
  63.  
  64. and the following keywords are recognized:
  65.  
  66.  FROM files       - specifies the object files that are the primary
  67.                     input to the linker.  These object files will
  68.                     always be copied to the root of the object
  69.                     module.  You must specify at least one object file
  70.                     for the root.  If it appears as the first option
  71.                     to BLINK then the FROM keyword is optional and may
  72.                     be omitted.  ROOT is an acceptable synonym for FROM.
  73.                     FROM may be used more than once with the files for
  74.                     each FROM adding to the list of files to be linked.
  75.  
  76.  TO file          - specifies target object module to create.  If
  77.                     omitted it defaults to the same name as the first
  78.                     object module listed on a FROM option with its .o
  79.                     suffix removed.
  80.  
  81.  WITH file        - specifies a file containing BLINK command options
  82.                     to be processed for this link.  More than one WITH
  83.                     file may be specified as may WITH files contain
  84.                     WITH statements.  The contents of all with files
  85.                     will be treated as if they were specified on the
  86.                     BLINK command line.
  87.  
  88.  VER file         - a destination file to contain all linker output
  89.                     messages.  If you do not specify it then all
  90.                     messages go to the terminal.
  91.  
  92.  LIBRARY files    - specifies the files to be scanned as libraries. 
  93.                     Only referenced segments from library files will
  94.                     be included in the final object module.  LIB is a
  95.                     valid synonym for LIBRARY.
  96.  
  97.  XREF file        - specifies a file to which the cross reference
  98.                     information will be written.  If not specified
  99.                     and a cross reference is requested with the MAP
  100.                     option, the cross reference listing will appear as
  101.                     part of the map file.
  102.  
  103.  FASTER           - a do-nothing option that is included only for
  104.                     ALINK compatibility.
  105.  
  106.  VERBOSE          - causes BLINK to print out the names of each file
  107.                     as it processes it.
  108.  
  109.  NODEBUG          - supresses any HUNK_DEBUG, symbol table
  110.                     information or hunk names in the final object
  111.                     file.  This is equivalent to the object file
  112.                     that would be produced if STRIPA were run on the
  113.                     final object file
  114.  
  115.  SMALLDATA        - causes all DATA and BSS sections to be Coalesced
  116.                     into a single hunk.  This is useful for combining all
  117.                     data hunks from a program into a single hunk - decreasing
  118.                     load time but potentially producing larger hunks that are
  119.                     difficult to scatter load
  120.  
  121.  SMALLCODE        - causes all CODE hunks to be Coalesced into a single hunk.
  122.  
  123.  WIDTH n          - sets the maximum line length for the map and cross
  124.                     reference listings.  This is useful when sending
  125.                     the output to a divice that has different line
  126.                     length requirements.  If not specified it defaults
  127.                     to 80.
  128.  
  129.  MAP file options - specifies a file to which a map is to be written.
  130.                     options controls which parts of the map will be
  131.                     written.  See the MAP section for more information.
  132.  
  133.  OVERLAY          - specifies the start of an overlay tree terminated
  134.                     by a line consisting of a single pound sign '#'.
  135.                     See the OVERLAY section for more information.
  136.  
  137.  
  138.  DEFINE          - allows for definition or re-definition of a symbol
  139.              Useful for stubbing yet unwritten routines, resolving 
  140.             unresolved references and link time patches to your
  141.             code. Possible combinations are: DEFINE symbola = 
  142.             symbolb where you want symbola to be resolved to symbolb
  143.                     and symbolb has been previously defined in your code.
  144.                     DEFINE symbola = some constant where the constant is
  145.                     either a decimal or hexadecimal number. If hexadecimal
  146.                     number is input it must be preceded with a $ sign. ie.
  147.                     DEFINE symbola = $dead or DEFINE symbola = 1234.         
  148.  
  149. Example Command Line Usage:
  150. ---------------------------
  151.  
  152. BLINK 
  153.  
  154. ==========
  155. WITH Files
  156. ==========
  157.  
  158. Although BLINK is completely compatible with ALINK WITH files the order
  159. and format used to input options is quite position independant. FROM files
  160. and LIBRARY options can span several lines with or without line continuation
  161. characters "+". I hope the examples below reflect this remarkable flexability.
  162. Gee a tool that is user-friendly. We must be doing something wrong !   
  163.  
  164. Example WITH files
  165. ------------------
  166.  
  167. from c.o vt100.o init.o window.o xmodem.o remote.o kermit.o script.o
  168. lib lib:lc.lib  lib:amiga.lib
  169. verbose smallcode smalldata
  170. to vt100
  171.  
  172. or yet another way
  173.  
  174. FROM c.o 
  175. vt100.o
  176. init.o window.o
  177. xmdem.o remote.o kermit.o script.o
  178. LIBRARY
  179. lib:lc.lib
  180. lib:lc.lib
  181. MAP ram:vt100.map
  182. TO df1:vt100/vt100
  183. SMALLCODE
  184. SMALLDATA
  185. VERBOSE
  186.  
  187.  
  188. or better yet, a standard sort of header WITH file that you can append
  189. the specifics to the end of the file and save some typing every time you
  190. need to create a WITH file.
  191.  
  192. LIBRARY
  193. ram:lc.lib
  194. ram:amiga.lib
  195. SMALLDATA
  196. SMALLCODE
  197. MAP
  198. ram:mymap
  199. VERBOSE
  200. XREF ram:myxref
  201. FROM c.o
  202. vt100.0 init.o window.o xmodem.o remote.o kermit.o script.o
  203.  
  204. In the above exmaple you will notice that no TO file was specified.
  205. BLINK will atomatically create a TO file for you in the current directory
  206. with the name of the first module in you FROM list no including the
  207. startup routine in this case c.o. So in the above example the executable
  208. will be called VT100 without the .o extension. Nice touch EH! 
  209.  
  210. ========
  211. Overlays
  212. ========
  213.  
  214. Not supported in this release
  215.  
  216. =========
  217. Map Files
  218. =========
  219. MAP <map file> <map options>
  220. <map options> are H S X F O PLAIN FANCY
  221. MAP [[filename],option,option,...]
  222.    filename   map output file
  223.    option     letter of report to produce (see below)
  224.  
  225. WIDTH n        columns allowed in map file (default 80)
  226. INDENT n    columns to indent on a line (included in width) (default 0)
  227.         default 0
  228. HEIGHT n    lines on a page in map file (0 indicates no pagenation)
  229.         (default 55)
  230. HWIDTH n    width of hunk names (default 8)
  231. FWIDTH n    width of file names (default 16)
  232. PWIDTH n    width of program unit names (default 8)
  233. SWIDTH n    width of symbol names (default 8)
  234. FANCY        flag to allow printer control characters in the map file
  235.         (this is the default condition)
  236. PLAIN        turns off the FANCY option
  237. BUFSIZE <n>
  238.  
  239. map:    map has sub keywords, they are:
  240.         h - MapHunk
  241.         s - MapSym
  242.         x - MapXref
  243.         f - MapFile
  244.         o - MapOvly
  245.     additionaly it will accept other keywords that
  246.     can have parameters:
  247.         width    - (1-132) def 80
  248.         height    - (1-255) def 55
  249.         Hwidth    - (1-255) def 8 (hunk name width)
  250.         Fwidth    - (1-255) def 16 (file name width)
  251.         Swidth    - (1-255) def 25 (Symbol width)
  252.         indent    - (1-255) def 0 (line indentation)
  253.  
  254.  
  255. ====================
  256. BLINK Error messages
  257. ====================
  258.   1 Parser failure.
  259.   2 Pass 1 failure.
  260.   4 Coalesce failure.
  261.   5 Map failure.
  262.   3 Pass 2 failure.
  263.   6 Symbol Initialization failure.
  264. 200 Out of memory!! 
  265. 300 Read error on file '%s' 
  266. 301 Write error on file '%s' 
  267. 400 *** Break: Blink terminating. 
  268. 425 Cannot find library %s 
  269. 426 Cannot find object %s 
  270. 444 Hunk_Symbol has bad %d symbol %s 
  271. 445 Invalid HUNK_SYMBOL %s 
  272. 446 Invalid symbol type %d for %s 
  273. 447 %s is a load file 
  274. 448 Invalid hunk #%d 
  275. 449 No hunk_end seen for %s 
  276. 501 Invalid Reloc 8 or 16 reference 
  277. 502 Distance for Reloc16 > 32768 
  278. 503 Distance for Reloc8 > 128 
  279. 504 Distance for Data Reloc16 > 32768 
  280. 505 Distance for Data Reloc8 > 128 
  281. 506 Can't locate resolved symbol %s 
  282. 507 Unknown Symbol type %d 
  283. 508 Symbol type %d unimplemented 
  284. 509 Unknown hunk type %d in Pass2 
  285. 600 Invalid command '%s' 
  286. 601 %s option specified more than once 
  287. 602 Unable to open map file '%s' 
  288. 603 %s is not a valid number 
  289. 604 with file is not readable 
  290. 605 Cannot open with file '%s' 
  291. 606 Unable to open output file '%s' 
  292. 607 No FROM/ROOT files specified 
  293. 999 Unknown internal error <<<let us know if you get this one
  294.  
  295. =============
  296. BLINK History
  297. =============
  298. 5.5 Released 18 August 1986
  299. 5.6 Released 20 August 1986
  300.    Fixed problem with map file generation
  301.    Fixed problem with map file error messages
  302. 5.7 Released 22 August 1986
  303.    Corrected incompatibilities with Lattice 3.02 and 3.03 generating extra
  304.       HUNK_ENDs.
  305.    Added TABS to the with file/command line parser
  306.    Fixed messages so last unresolved reference is not overwritten by VERBOSE
  307.       messages in PASS2.
  308. 6.0 Unreleased
  309.    Added support for patching reloc16s to allow that -r option of Lattice to
  310.       used with Blink.
  311.    Rewrote map sorting algorithm to significantly cut map generation time.
  312.    Corrected various parser bugs.
  313.    Added ability to BLINK files linked with ALINK
  314. 6.1 Unreleased
  315.    Added link time to map page headers.
  316.    Added define statement.
  317.    Corrected problems in handling of CHIP and FAST hunk types
  318. 6.2 Unreleased
  319.    Rewrote algorithm for patching reloc16s.
  320.    Moved map to after pass2.
  321.    Reduced memory usage by changing required alignment boundary from 4 to 2.
  322.    Added suppression of dummy entry hunk.
  323.    Added default TO file logic.
  324. 6.3 Unreleased
  325.    Enhanced algorighm for pathing reloc16s to produce optimal size in two
  326.       passes.
  327.    Reduced size of patch jumps to 6 bytes.
  328.    Added support for allowing startup code to initialize BSS section.
  329.    Added support to allow startup code to produce a completely reentrant
  330.       module to be used with 1.2 resident command.
  331.    Added minimum size for memory requests to reduce likelyhood of a GURU when
  332.       system is too tight on memory.  If less than 1K contiguous is available,
  333.       BLINK will terminate.
  334. 6.4 Released 22 September 1986
  335.    Added cross reference of libraries to the map
  336.    Major clean up oc return code checking internally
  337.    Reduced large sections of code
  338.    Deleted REACH and REALREACH keywords from parser.
  339.    Corrected suppressing of dummy entry hunk.
  340.